<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
    <meta http-equiv="content-type" content="text/html; charset=UTF-8"/>
    <title>Creating source files - Zend Framework Manual</title>

    <link href="../css/shCore.css" rel="stylesheet" type="text/css" />
    <link href="../css/shThemeDefault.css" rel="stylesheet" type="text/css" />
    <link href="../css/styles.css" media="all" rel="stylesheet" type="text/css" />
</head>
<body>
<h1>Zend Framework</h1>
<h2>Programmer's Reference Guide</h2>
<ul>
    <li><a href="../en/zend.translate.sourcecreation.html">Inglês (English)</a></li>
    <li><a href="../pt-br/zend.translate.sourcecreation.html">Português Brasileiro (Brazilian Portuguese)</a></li>
</ul>
<table width="100%">
    <tr valign="top">
        <td width="85%">
            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.using.html">Using Translation Adapters</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.additional.html">Additional features for translation</a></div>
                    </td>
                </tr>
            </table>
<hr />
<div id="zend.translate.sourcecreation" class="section"><div class="info"><h1 class="title">Creating source files</h1></div>
    

    <p class="para">
        Below you will find a description of the different source formats
        which can be used with <span class="classname">Zend_Translate</span>.
    </p>

    <blockquote class="note"><p><b class="note">Note</b>: 
        <p class="para">
            Note that most of the described formats should be created by using
            a tool or a generation process. These Tools and processes are not part
            of Zend Framework and for most of the described formats free tools
            are available.
        </p>
    </p></blockquote>

    <div class="section" id="zend.translate.sourcecreation.array"><div class="info"><h1 class="title">Creating Array source files</h1></div>
        

        <p class="para">
            Array source files are plain arrays. But you have to define them
            manually since there is no tool to aid this.
            But because they are so simple, it&#039;s the fastest way to look up
            messages if your code works as expected. It&#039;s generally the best
            adapter to get started with translation business.
        </p>

        <pre class="programlisting brush: php">
$english = array(
    &#039;message1&#039; =&gt; &#039;message1&#039;,
    &#039;message2&#039; =&gt; &#039;message2&#039;,
    &#039;message3&#039; =&gt; &#039;message3&#039;);

$german = array(
    &#039;message1&#039; =&gt; &#039;Nachricht1&#039;,
    &#039;message2&#039; =&gt; &#039;Nachricht2&#039;,
    &#039;message3&#039; =&gt; &#039;Nachricht3&#039;);

$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; $english,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
$translate-&gt;addTranslation(array(&#039;content&#039; =&gt; $german, &#039;locale&#039; =&gt; &#039;de&#039;));
</pre>


        <p class="para">
            Since release 1.5 it is also supported to have arrays included within an external file.
            You just have to provide the filename and <span class="classname">Zend_Translate</span> will
            automatically include it and look for the array. See the following example for details:
        </p>

        <pre class="programlisting brush: php">
// myarray.php
return array(
    &#039;message1&#039; =&gt; &#039;Nachricht1&#039;,
    &#039;message2&#039; =&gt; &#039;Nachricht2&#039;,
    &#039;message3&#039; =&gt; &#039;Nachricht3&#039;);

// controller
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;array&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/myarray.php&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
</pre>


        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                Files which do not return an array will fail to be included.
                Also any output within this file will be ignored and suppressed.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.translate.sourcecreation.gettext"><div class="info"><h1 class="title">Creating Gettext source files</h1></div>
        

        <p class="para">
            Gettext source files are created by GNU&#039;s gettext library.
            There are several free tools available that can parse your
            code files and create the needed gettext source files.
            These have the extension <em class="emphasis">*.mo</em>
            and they are binary files.
            An open source tool for creating the files is
            <a href="http://sourceforge.net/projects/poedit/" class="link external">&raquo; poEdit</a>.
            This tool also supports you during the translation process itself.
        </p>

        <pre class="programlisting brush: php">
// We accume that we have created the mo files and translated them
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/english.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;/path/to/german.mo&#039;,
        &#039;locale&#039; =&gt; &#039;de&#039;
    )
);
</pre>


        <p class="para">
            As you can see the adapters are used exactly the same way,
            with one small difference:
            change <em class="emphasis">array</em> to <em class="emphasis">gettext</em>. All other usages are
            exactly the same as with all other adapters.
            With the gettext adapter you no longer have to be aware of
            gettext&#039;s standard directory structure,
            bindtextdomain and textdomain.
            Just give the path and filename to the adapter.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                 You should always use UTF-8 as source encoding.
                 Otherwise you will have problems when using two
                 different source encodings.
                 E.g. one of your source files is encoded
                 with ISO-8815-11 and another one with CP815.
                 You can set only one encoding for your source file,
                 so one of your languages probably will not display correctly.
            </p>

            <p class="para">
                 UTF-8 is a portable format which supports all languages.
                 When using UTF-8 for all languages, you will eliminate
                 the problem of incompatible encodings.
            </p>
        </p></blockquote>

        <p class="para">
            Many gettext editors add adapter informations as empty translation string.
            This is the reason why empty strings are not translated when using the
            gettext adapter. Instead they are erased from the translation table and
            provided by the  <span class="methodname">getAdapterInfo()</span> method. It will return
            the adapter informations for all added gettext files as array using the
            filename as key.
        </p>

        <pre class="programlisting brush: php">
// Getting the adapter informations
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;gettext&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/english.mo&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
print_r($translate-&gt;getAdapterInfo());
</pre>

    </div>

    <div class="section" id="zend.translate.sourcecreation.tmx"><div class="info"><h1 class="title">Creating TMX source files</h1></div>
        

        <p class="para">
            TMX source files are a new industry standard.
            They have the advantage of being <acronym class="acronym">XML</acronym> files and so they are
            readable by every editor and of course by humans.
            You can either create TMX files manually with a text editor,
            or you can use a special tool. But most tools currently available for
            creating TMX source files are not freely available.
        </p>

        <div class="example" id="zend.translate.sourcecreation.tmx.example"><div class="info"><p><b>Example #1 Example TMX file</b></p></div>
            

            <pre class="programlisting brush: xml">
&lt;?xml version=&quot;1.0&quot; ?&gt;
&lt;!DOCTYPE tmx SYSTEM &quot;tmx14.dtd&quot;&gt;
&lt;tmx version=&quot;1.4&quot;&gt;
   &lt;header creationtoolversion=&quot;1.0.0&quot; datatype=&quot;winres&quot; segtype=&quot;sentence&quot;
           adminlang=&quot;en-us&quot; srclang=&quot;de-at&quot; o-tmf=&quot;abc&quot;
           creationtool=&quot;XYZTool&quot; &gt;
   &lt;/header&gt;
   &lt;body&gt;
       &lt;tu tuid=&#039;message1&#039;&gt;
           &lt;tuv xml:lang=&quot;de&quot;&gt;&lt;seg&gt;Nachricht1&lt;/seg&gt;&lt;/tuv&gt;
           &lt;tuv xml:lang=&quot;en&quot;&gt;&lt;seg&gt;message1&lt;/seg&gt;&lt;/tuv&gt;
       &lt;/tu&gt;
       &lt;tu tuid=&#039;message2&#039;&gt;
           &lt;tuv xml:lang=&quot;de&quot;&gt;&lt;seg&gt;Nachricht2&lt;/seg&gt;&lt;/tuv&gt;
           &lt;tuv xml:lang=&quot;en&quot;&gt;&lt;seg&gt;message2&lt;/seg&gt;&lt;/tuv&gt;
       &lt;/tu&gt;
   &lt;/body&gt;
&lt;/tmx&gt;
</pre>


            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;tmx&#039;,
        &#039;content&#039; =&gt; &#039;path/to/mytranslation.tmx&#039;,
        &#039;locale&#039;  =&gt; &#039;en&#039;
    )
);
</pre>

        </div>

        <p class="para">
            TMX files can have several languages within the same file.
            All other included languages are added automatically,
            so you do not have to call  <span class="methodname">addLanguage()</span>.
        </p>

        <p class="para">
            If you want to have only specified languages from the source translated you can
            set the option <span class="property">defined_language</span> to <b><tt>TRUE</tt></b>.
            With this option you can add the wished languages explicitly with
             <span class="methodname">addLanguage()</span>. The default value for this option is to add all
            languages.
        </p>

        <blockquote class="note"><p><b class="note">Note</b>: <span class="info"><b>Option useId</b><br /></span>
            

            <p class="para">
                When you set the <em class="emphasis">useId</em> option to <b><tt>FALSE</tt></b>
                then the <em class="emphasis">srclang</em> header will be used to define the language
                which sets the message.
            </p>

            <p class="para">
                In our example the message key would <em class="emphasis">message1</em> per default.
                When this option is set to <b><tt>FALSE</tt></b> the message key
                <em class="emphasis">Nachricht1</em> would be used.
            </p>

            <p class="para">
                Note that the <em class="emphasis">tuv</em> entry which is related to the
                <em class="emphasis">srclang</em> entry must be the first
                <em class="emphasis">tuv</em> entry which is set like shown in the above example.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.translate.sourcecreation.csv"><div class="info"><h1 class="title">Creating CSV source files</h1></div>
        

        <p class="para">
            CSV source files are small and human readable.
            If your customers want to translate their own,
            you will probably use the CSV adapter.
        </p>

        <div class="example" id="zend.translate.sourcecreation.csv.example"><div class="info"><p><b>Example #2 Example CSV file</b></p></div>
            

            <pre class="programlisting brush: txt">
﻿#Example csv file
message1;Nachricht1
message2;Nachricht2
</pre>


            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;csv&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/mytranslation.csv&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;path/to/other.csv&#039;,
        &#039;locale&#039; =&gt; &#039;fr&#039;
    )
);
</pre>

        </div>

        <p class="para">
            There are three different options for the CSV adapter.
            You can set <span class="property">delimiter</span>, <span class="property">limit</span> and
            <span class="property">enclosure</span>.
        </p>

        <p class="para">
            The default delimiter for CSV string is &#039;<em class="emphasis">;</em>&#039;, but
            with the option <span class="property">delimiter</span>
            you can decide to use another one.
        </p>

        <p class="para">
            The default limit for a line within a CSV file is &#039;<em class="emphasis">0</em>&#039;. This means
            that the end of a CSV line is searched automatically. If you set
            <span class="property">limit</span> to any value, then the CSV file will be
            read faster, but any line exceeding this limit will be truncated.
        </p>

        <p class="para">
            The default enclosure to use for CSV files is &#039;<em class="emphasis">&quot;</em>&#039;. You can
            set a different one using the option <span class="property">enclosure</span>.
        </p>

        <div class="example" id="zend.translate.sourcecreation.csv.example2"><div class="info"><p><b>Example #3 Second CSV file example</b></p></div>
            

            <pre class="programlisting brush: txt">
﻿# Example CSV file
&quot;message,1&quot;,Nachricht1
message2,&quot;Nachricht,2&quot;
&quot;message3,&quot;,Nachricht3
</pre>


            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;csv&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/mytranslation.csv&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;,
        &#039;delimiter&#039; =&gt; &#039;,&#039;
    )
);

$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;/path/to/other.csv&#039;,
        &#039;locale&#039; =&gt; &#039;fr&#039;
    )
);
</pre>

        </div>

        <blockquote class="note"><p><b class="note">Note</b>: 
            <p class="para">
                When you are using non-ASCII characters within your CSV file, like umlauts or UTF-8
                chars, then you should always use enclosure. Omitting the enclosure can lead to
                missing characters in your translation.
            </p>
        </p></blockquote>
    </div>

    <div class="section" id="zend.translate.sourcecreation.ini"><div class="info"><h1 class="title">Creating INI source files</h1></div>
        

        <p class="para">
            <acronym class="acronym">INI</acronym> source files are human readable but normally not very small as
            they also include other data beside translations. If you have data which shall be
            editable by your customers you can use the <acronym class="acronym">INI</acronym> adapter.
        </p>

        <div class="example" id="zend.translate.sourcecreation.ini.example"><div class="info"><p><b>Example #4 Example INI file</b></p></div>
            

            <pre class="programlisting brush: txt">
[Test]
;TestPage Comment
Message_1=&quot;Nachricht 1 (de)&quot;
Message_2=&quot;Nachricht 2 (de)&quot;
Message_3=&quot;Nachricht :3 (de)&quot;
</pre>


            <pre class="programlisting brush: php">
$translate = new Zend_Translate(
    array(
        &#039;adapter&#039; =&gt; &#039;ini&#039;,
        &#039;content&#039; =&gt; &#039;/path/to/mytranslation.ini&#039;,
        &#039;locale&#039;  =&gt; &#039;de&#039;
    )
);
$translate-&gt;addTranslation(
    array(
        &#039;content&#039; =&gt; &#039;/path/to/other.ini&#039;,
        &#039;locale&#039; =&gt; &#039;it&#039;
    )
);
</pre>

        </div>

        <p class="para">
            <acronym class="acronym">INI</acronym> files have several restrictions. If a value in the
            <acronym class="acronym">INI</acronym> file contains any non-alphanumeric characters it needs to be
            enclosed in double-quotes (<em class="emphasis">&quot;</em>). There are also reserved words which
            must not be used as keys for <acronym class="acronym">INI</acronym> files. These include:
            <b><tt>NULL</tt></b>, yes, no, <b><tt>TRUE</tt></b>, and
            <b><tt>FALSE</tt></b>. Values <b><tt>NULL</tt></b>, <em class="emphasis">no</em>
            and <b><tt>FALSE</tt></b> results in <em class="emphasis">&quot;&quot;</em>,
            <em class="emphasis">yes</em> and <b><tt>TRUE</tt></b> results in &#039;1&#039;. Characters
            <em class="emphasis">{}|&amp;~![()&quot;</em> must not be used anywhere in the key and have a
            special meaning in the value. Do not use them as it will produce unexpected behaviour.
        </p>
    </div>
</div>
        <hr />

            <table width="100%">
                <tr>
                    <td width="25%" style="text-align: left;">
                    <a href="zend.translate.using.html">Using Translation Adapters</a>
                    </td>

                    <td width="50%" style="text-align: center;">
                        <div class="up"><span class="up"><a href="zend.translate.html">Zend_Translate</a></span><br />
                        <span class="home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></span></div>
                    </td>

                    <td width="25%" style="text-align: right;">
                        <div class="next" style="text-align: right; float: right;"><a href="zend.translate.additional.html">Additional features for translation</a></div>
                    </td>
                </tr>
            </table>
</td>
        <td style="font-size: smaller;" width="15%"> <style type="text/css">
#leftbar {
	float: left;
	width: 186px;
	padding: 5px;
	font-size: smaller;
}
ul.toc {
	margin: 0px 5px 5px 5px;
	padding: 0px;
}
ul.toc li {
	font-size: 85%;
	margin: 1px 0 1px 1px;
	padding: 1px 0 1px 11px;
	list-style-type: none;
	background-repeat: no-repeat;
	background-position: center left;
}
ul.toc li.header {
	font-size: 115%;
	padding: 5px 0px 5px 11px;
	border-bottom: 1px solid #cccccc;
	margin-bottom: 5px;
}
ul.toc li.active {
	font-weight: bold;
}
ul.toc li a {
	text-decoration: none;
}
ul.toc li a:hover {
	text-decoration: underline;
}
</style>
 <ul class="toc">
  <li class="header home"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="manual.html">Guia de Refer&ecirc;ncia do Programador</a></li>
  <li class="header up"><a href="reference.html">Refer&ecirc;ncia do Zend Framework</a></li>
  <li class="header up"><a href="zend.translate.html">Zend_Translate</a></li>
  <li><a href="zend.translate.introduction.html">Introduction</a></li>
  <li><a href="zend.translate.adapter.html">Adapters for Zend_Translate</a></li>
  <li><a href="zend.translate.using.html">Using Translation Adapters</a></li>
  <li class="active"><a href="zend.translate.sourcecreation.html">Creating source files</a></li>
  <li><a href="zend.translate.additional.html">Additional features for translation</a></li>
  <li><a href="zend.translate.plurals.html">Plural notations for Translation</a></li>
 </ul>
 </td>
    </tr>
</table>

<script type="text/javascript" src="../js/shCore.js"></script>
<script type="text/javascript" src="../js/shAutoloader.js"></script>
<script type="text/javascript" src="../js/main.js"></script>

</body>
</html>